Documentation Fields
Time to cover the basic fields that apply to all documents. These fields are specified using the '@' character and constitute key value pairs used in rendering your final document.
Documentation is generated through providing the parser with key value pairs. Let's take a look at a few examples:
@id ng.filter:limitTo
@name Sweet Title
@ngdoc directive
@doc overview
@description ## My Markdown Title! Here is a markdown list * Yay * Cool * Awesome
In every case there is a key next to the "@" symbol and then the value is everything after the key until the next key is found, the code block ends, or the next documentation identifier is encountered. Multiline is supported but is typically used most often for "@description" type keys.
We have covered identifiers in a previous article. But let's talk more about the docType values.
This is important to remember. Often times you can get wrapped up in the "@id" given to a document. For example:
@ngdoc filter @name ng.filter:limitTo
It can be tempting to look at a name/id and assume this document will be rendered as a "filter", but it is the value associated with the document identifier
( @ngdoc filter
) that determines which rendering method is used to generate the html for this document.
Here are the default docTypes for the "@doc" documentation plugin which are inherited by all documentation plugins including the AngularJS documentation plugin.
Here are are docTypes added by the "@ngdoc" AngularJS documentation plugin
function
from the default plugin to provide a different experience for displaying the function
docType.Picture all these key value pairs getting parsed out and stored in a nice pretty json object. Then this json object needs to be rendered into html. Well, the docType is the identifier that determines which rendering function gets to grab onto all these attributes of this object to spit out html! Easy peezy lemon squeezy.
The id
is a system used identifier for this doc. It appears in urls and in filenames. It can also determine where the document is placed in terms of grouping unless the docType is "overview" or unless the id
value is "index". We'll talk more about that later :-)
The name
is the user friendly title of the document. If no id
is provided, then the name
also becomes the id
. This is helpful in API documentation when you really want the name and the id to be the same.
The description
is the meat and potatoes. The description is typically parsed via "Showdown", a NodeJS implementation of markdown. It is a multiline value that provides really whatever you want. One caveat is that you DO NOT want to put markup within markdown! If you need to use markup in your description, then make sure it will not be a child of any markdown or you will get unpredictable results. Taking a look at the source of this documentation will give you a good idea of how to balance markup and markdown. Naturally, sticking with markdown will be lighter weight and will provide more consistency within the ui.